home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 014 / columns3.arc / COLUMNS.DOC < prev   
Text File  |  1986-07-07  |  11KB  |  361 lines
  1.    COLUMNS 3.0                                                  July 1, 1986
  2.  
  3.  
  4.    DESCRIPTION:
  5.    ===========
  6.  
  7.    COLUMNS  is a general purpose MS-DOS filter that reads a sequential input
  8.    file, reformats it in a columnar fashion, and writes the result to a  new
  9.    sequential file.  It reads the input file from standard in, and sends the
  10.    output  file  to  standard  out.   This  allows it to be used with MS-DOS
  11.    piping.  It is driven by a control file and produces a  small  report  of
  12.    statistics  or  errors  back  to  the standard error device, normally the
  13.    terminal.  It supports both character and hex input  for  columns  to  be
  14.    inserted in the output file. 
  15.  
  16.    (C) Copyright 1986 by Bill Prew, ALL RIGHTS RESERVED
  17.  
  18.    Please refer all inquiries to:
  19.        Bill Prew
  20.        1615 Pawtucket Ave
  21.        Rumford RI 02916
  22.  
  23.  
  24.    You may copy and distribute this program freely, provided that:
  25.        <1> No fee is charged for such copying and distribution, and
  26.        <2> It is distributed ONLY in its original, unmodified state.
  27.  
  28.    This  program  is  being  distributed as user supported software.  If you
  29.    like this program, and find it of use, then  your  contribution  will  be
  30.    appreciated.   If you are using this product in a commercial environment,
  31.    then the contribution is not voluntary.  If you would like the source for
  32.    the program send a mailer and $10 to the address above with  a  formatted
  33.    floppy. 
  34.  
  35.  
  36.    USAGE:
  37.    =====
  38.    The command format to execute the program is;
  39.  
  40.    COLUMNS <input-filename >output-filename control-filename
  41.  
  42.    where  input-filename  is  the  input  file, output-filename is the newly
  43.    created  file  after  all  column  commands  have   been   applied,   and
  44.    control-filename  is  the  name  of  the  file  that contains the replace
  45.    commands and options. 
  46.  
  47.  
  48.    CONTROL CARD FORMATS:
  49.    ====================
  50.    The general format of the control cards is;
  51.  
  52.    type,parms
  53.  
  54.    where type can be "opts", "cols", "text" or "hex" as discussed below, and
  55.    parms are different parameters and information needed  by  the  different
  56.    control cards. 
  57.  
  58.  
  59.  
  60.                                     Page 1                                  
  61.    COLUMNS 3.0                                                  July 1, 1986
  62.  
  63.  
  64.        "OPTS" CONTROL CARD:
  65.        -------------------
  66.        This card selects several options for the run with the format;
  67.  
  68.        opts,[pad | nopad]
  69.  
  70.        pad ............... this  preserves  trailing  spaces  in  the output
  71.                            records. 
  72.  
  73.        nopad ............. this causes all trailing spaces to be  eliminated
  74.                            from  the  output records before they are written
  75.                            (this is the default). 
  76.  
  77.  
  78.        "COLS" CONTROL CARD:
  79.        --------------------
  80.        This is the most used card in columns control files and  specifies  a
  81.        set  of columns to be moved to the output record.  The output line is
  82.        built in a left to right  fashion  depending  on  the  control  cards
  83.        specified. 
  84.  
  85.        cols,start-column,number
  86.  
  87.        start-column ...... this  specifies  the character position (relative
  88.                            to one) in the input record to  start  moving  to
  89.                            the output record. 
  90.  
  91.        number ............ this  is  the  number  of  columns  (starting  at
  92.                            start-column) that will be moved  to  the  output
  93.                            line for each record. 
  94.  
  95.  
  96.        "TEXT" CONTROL CARD:
  97.        --------------------
  98.        This card is used to insert new text strings in the output records at
  99.        the current column. 
  100.  
  101.        text,'insert-string'
  102.  
  103.        ' ................. notice  the  three  single  quotes  in the parms.
  104.                            this is the delimiter and bounds the new and  old
  105.                            strings.   it  can  be  any character, as long as
  106.                            both are the same. 
  107.  
  108.        insert-string ..... this is the new text to insert  into  the  output
  109.                            record at the current column. 
  110.  
  111.  
  112.        "HEX" CONTROL CARD:
  113.        -------------------
  114.        This card is used to insert new text strings in the output records at
  115.        the  current  column.   This  card is very similar to the "text" card
  116.        except it allows you to specify the old and new strings as hex  data.
  117.        The format is;
  118.  
  119.  
  120.                                     Page 2                                  
  121.    COLUMNS 3.0                                                  July 1, 1986
  122.  
  123.  
  124.        hex,insert-hex-string
  125.  
  126.        insert_hex_string . this  is  the  new text to insert into the output
  127.                            record at the current column, in hex format.  for
  128.                            example 414243 would place ABC into  aech  output
  129.                            record at the current column. 
  130.  
  131.  
  132.    EXAMPLES:
  133.    =========
  134.  
  135.        EXAMPLE 1:
  136.        ----------
  137.  
  138.            COLUMNS <in >out columns.ctl
  139.  
  140.            columns.ctl ....... text,'XXXX'
  141.                                cols,1,4
  142.                                hex,3132333435
  143.  
  144.            in ................ YYYY
  145.                                ZZZZ
  146.  
  147.            out ............... XXXXYYYY12345
  148.                                XXXXZZZZ12345
  149.  
  150.        This  is  pretty straight forward, the output record is built up from
  151.        the string "XXXX", then columns 1 through 5 of the input record,  and
  152.        finaly the string "12345". 
  153.  
  154.        EXAMPLE 2:
  155.        ----------
  156.  
  157.            COLUMNS <in >out columns.ctl
  158.  
  159.            columns.ctl ....... cols,1,4
  160.                                hex,0d0a
  161.                                cols,5,4
  162.                                hex,0d0a
  163.  
  164.            in ................ AAAABBBB
  165.                                CCCCDDDD
  166.  
  167.            out ............... AAAA
  168.                                BBBB
  169.                                CCCC
  170.                                DDDD
  171.  
  172.        This  is a little trickier.  By inserting a line-feed carraige-return
  173.        between the first 4 columns and the second four columns  we  actually
  174.        split the input line into two output lines. 
  175.  
  176.        EXAMPLE 3:
  177.        ----------
  178.  
  179.  
  180.                                     Page 3                                  
  181.    COLUMNS 3.0                                                  July 1, 1986
  182.  
  183.  
  184.            COLUMNS <in >out columns.ctl
  185.  
  186.            columns.ctl ....... text,'copy '
  187.                                cols,1,8
  188.                                text,'.old '
  189.                                cols,1,8
  190.                                text,'.new'
  191.  
  192.            in ................ file1
  193.                                file2
  194.                                file3
  195.  
  196.            out ............... copy file1   .old file1   .new
  197.                                copy file2   .old file2   .new
  198.                                copy file3   .old file3   .new
  199.  
  200.        Notice  that  you  can  reuse  the same columns from the input record
  201.        multiple times in the output record. 
  202.  
  203.        EXAMPLE 4:
  204.        ----------
  205.  
  206.            FILATR a: | COLUMNS >out columns.ctl
  207.  
  208.            replace.ctl ....... cols,22,9
  209.                                text,' ---> '
  210.                                cols,1,12
  211.  
  212.            FILATR output ..... MS-DOS File Attribute Utility version 2.12
  213.                                 
  214.                                loader.sys           . S R H .
  215.                                io.sys               . S R H .
  216.                                msdos.sys            . S R H .
  217.                                command.com          . . . . .
  218.                                config.sys           A . . . .
  219.                                autoexec.bat         . . . . .
  220.                                 
  221.                                6 files
  222.  
  223.           out ............... Utility  ---> MS-DOS File
  224.                                      ty  --->
  225.                                . S R H . ---> loader.sys
  226.                                . S R H . ---> io.sys
  227.                                . S R H . ---> msdos.sys
  228.                                . . . . . ---> command.com
  229.                                A . . . . ---> config.sys
  230.                                . . . . . ---> autoexec.bat
  231.                                      . . --->
  232.                                      . . ---> 6 files
  233.  
  234.        This example demonstrates the support of piping to  pass  the  output
  235.        from one command into the COLUMNS program. 
  236.  
  237.  
  238.  
  239.  
  240.                                     Page 4                                  
  241.    COLUMNS 3.0                                                  July 1, 1986
  242.  
  243.  
  244.    NOTES:
  245.    =====
  246.        <1> The  input  record  is  not  altered  as the program rebuilds the
  247.        output line, so it is possible to have column ranges that overlap, or
  248.        use the same input line columns more than once in the control file. 
  249.  
  250.  
  251.    LIMITS:
  252.    ======
  253.        Maximum input/output record length = 2000 bytes
  254.  
  255.        Maximum number of control cards = 100
  256.  
  257.        Maximum length of strings on 'text'/'hex' control cards = 100 bytes
  258.  
  259.        Binary data is supported with the exception of  line-feed  chars,  as
  260.        these  are used as in MS-DOS to end logical records in the sequential
  261.        file.  These will confuse the program if  they  exist  in  the  input
  262.        record. 
  263.  
  264.  
  265.    RELEASE INFO:
  266.    ============
  267.  
  268.    RELEASE 3.0
  269.  
  270.        <1> The  program  was completely re-written using Lattice version 3.0
  271.        for speed and added flexibility.  This release runs  3  to  10  times
  272.        faster than release 2.0. 
  273.  
  274.        <2> The  program was changed to support MS-DOS redirection and piping
  275.        for it's input and output filenames.  It now reads  it's  input  from
  276.        Standard Input and writes it's output to Standard Output. 
  277.  
  278.        <3> The  program now supports record lengths up to 2000 characters in
  279.        length. 
  280.  
  281.        <4> The control  card  format  was  changed  slightly  to  allow  any
  282.        character  to  be  used  as  the  text string delimiter.  This allows
  283.        double quotes to be part of the replace strings by using  some  other
  284.        delimiter character. 
  285.  
  286.    RELEASE 2.0
  287.  
  288.        <1> The  statistics  are now displayed directly to the screen instead
  289.        of being written to the COLUMNS.PRN file. 
  290.  
  291.        <2> The control file name no  longer  has  to  be  COLUMNS.CTL.   Any
  292.        filename  can  be  entered  on  the  command  line  such  as "COLUMNS
  293.        TEST.CTL".  If no name is  entered,  COLUMNS.CTL  is  still  used  by
  294.        default. 
  295.  
  296.        <3> The program has been re-written a bit and now runs in almost half
  297.        the time of the initial version. 
  298.  
  299.  
  300.                                     Page 5                                  
  301.    COLUMNS 3.0                                                  July 1, 1986
  302.  
  303.  
  304.        <4> Error reporting has been greatly improved. 
  305.  
  306.    RELEASE 1.0
  307.  
  308.        <1> This was the initial release. 
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.                                     Page 6                                  
  361.